Crate taffy

source ·
Expand description

§Taffy

Taffy is a flexible, high-performance library for UI layout. It currently implements the Flexbox, Grid and Block layout algorithms from the CSS specification. Support for other paradigms is planned. For more information on this and other future development plans see the roadmap issue.

§Architecture

Taffy is based on a tree of “UI nodes” similar to the tree of DOM nodes that one finds in web-based UI. Each node has:

  • A Style struct which holds a set of CSS styles which function as the primary input to the layout computations.
  • A Layout struct containing a position (x/y) and a size (width/height) which function as the output of the layout computations.
  • Optionally:
    • A Vec set of child nodes
    • “Context”: arbitrary user-defined data (which you can access when using a “measure function” to integrate Taffy with other kinds of layout such as text layout)

Usage of Taffy consists of constructing a tree of UI nodes (with associated styles, children and context), then calling function(s) from Taffy to translate those styles, parent-child relationships and measure functions into a size and position in 2d space for each node in the tree.

§High-level API vs. Low-level API

Taffy has two APIs: a high-level API that is simpler and easier to get started with, and a low-level API that is more flexible gives greater control. We would generally recommend the high-level API for users using Taffy standalone and the low-level API for users wanting to embed Taffy as part of a wider layout system or as part of a UI framework that already has it’s own node/widget tree representation.

§High-level API

The high-level API consists of the TaffyTree struct which contains a tree implementation and provides methods that allow you to construct a tree of UI nodes. Once constructed, you can call the compute_layout_with_measure method to compute the layout (passing in a “measure function” closure which is used to compute the size of leaf nodes), and then access the layout of each node using the layout method.

When using the high-level API, Taffy will take care of node storage, caching and dispatching to the correct layout algorithm for a given node for you. See the TaffyTree struct for more details on this API.

Examples which show usage of the high-level API include:

In particular, the “measure” example shows how to integrate Taffy layout with other layout modalities such as text or image layout when using the high level API.

§Low-level API

The low-level API consists of a set of traits (notably the LayoutPartialTree trait) which define an interface behind which you must implement your own tree implementation, and a set of functions such as compute_flexbox_layout and compute_grid_layout which implement the layout algorithms (for a single node at a time), and are designed to be flexible and easy to integrate into a wider layout or UI system.

When using this API, you must handle node storage, caching, and dispatching to the correct layout algorithm for a given node yourself. See the crate::tree::traits module for more details on this API.

Examples which show usage of the low-level API are:

  • custom_tree_vec which implements a custom Taffy tree using a Vec as an arena with NodeId’s being index’s into the Vec.
  • custom_tree_owned_partial which implements a custom Taffy tree using directly owned children with NodeId’s being pointers.
  • custom_tree_owned_unsafe which implements a custom Taffy tree using directly owned children with NodeId’s being pointers.

§Feature Flags

§Algorithms

  • block_layout (enabled by default) — Enables the Block layout algorithm. See compute_block_layout.
  • flexbox (enabled by default) — Enables the Flexbox layout algorithm. See compute_flexbox_layout.
  • grid (enabled by default) — Enables the CSS Grid layout algorithm. See compute_grid_layout.
  • content_size (enabled by default) — Causes all algorithms to compute and output a content size for each node

§Taffy Tree

  • taffy_tree (enabled by default) — Enable the built-in Taffy node tree. See TaffyTree.

§Other

  • serde — Add serde derives to Style structs
  • std (enabled by default) — Allow Taffy to depend on the Rust Standard Library
  • alloc — Allow Taffy to depend on the alloc library
  • debug — Internal feature for debugging
  • profile — Internal feature for profiling

Re-exports§

Modules§

  • compute
    Low-level access to the layout algorithms themselves. For a higher-level API, see the TaffyTree struct.
  • geometry
    Geometric primitives useful for layout
  • prelude
    Commonly used types
  • style
    A typed representation of CSS style properties in Rust. Used as input to layout computation.
  • style_helpers
    Helper functions which it make it easier to create instances of types in the style and geometry modules.
  • tree
    Contains both a high-level interface to Taffy using a ready-made node tree, and a set of traits for defining custom node trees.
  • util
    Helpful misc. utilities such as a function to debug print a tree

Structs§

  • Style
    A typed representation of the CSS style information for a single node.
  • TaffyTreetaffy_tree
    An entire tree of UI nodes. The entry point to Taffy’s high-level API.

Traits§

  • LayoutPartialTree
    Any type that implements LayoutPartialTree can be laid out using Taffy’s algorithms
  • PrintTree
    Trait used by the print_tree method which prints a debug representation
  • RoundTree
    Trait used by the round_layout method which takes a tree of unrounded float-valued layouts and performs rounding to snap the values to the pixel grid.
  • TraversePartialTree
    This trait is Taffy’s abstraction for downward tree traversal. However, this trait does not require access to any node’s other than a single container node’s immediate children unless you also intend to implement TraverseTree.
  • TraverseTree
    A marker trait which extends TraversePartialTree with the additional guarantee that the child/children methods can be used to recurse infinitely down the tree. Is required by the RoundTree and the PrintTree traits.

Functions§